home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kparts / partmanager.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  8.7 KB  |  290 lines
  1. // -*- mode: c++; c-basic-offset: 2 -*-
  2. /* This file is part of the KDE project
  3.    Copyright (C) 1999 Simon Hausmann <hausmann@kde.org>
  4.              (C) 1999 David Faure <faure@kde.org>
  5.  
  6.    This library is free software; you can redistribute it and/or
  7.    modify it under the terms of the GNU Library General Public
  8.    License as published by the Free Software Foundation; either
  9.    version 2 of the License, or (at your option) any later version.
  10.  
  11.    This library is distributed in the hope that it will be useful,
  12.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14.    Library General Public License for more details.
  15.  
  16.    You should have received a copy of the GNU Library General Public License
  17.    along with this library; see the file COPYING.LIB.  If not, write to
  18.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19.    Boston, MA 02110-1301, USA.
  20. */
  21. #ifndef __kpartmanager_h__
  22. #define __kpartmanager_h__
  23.  
  24. #include <qobject.h>
  25. #include <qwidget.h>
  26. #include <qptrlist.h>
  27.  
  28. #include <kdelibs_export.h>
  29.  
  30. class KInstance;
  31.  
  32. namespace KParts
  33. {
  34.  
  35. class Part;
  36.  
  37. class PartManagerPrivate;
  38.  
  39. /**
  40.  * The part manager is an object which knows about a collection of parts
  41.  * (even nested ones) and handles activation/deactivation.
  42.  *
  43.  * Applications that want to embed parts without merging GUIs
  44.  * only use a KParts::PartManager. Those who want to merge GUIs use a
  45.  * KParts::MainWindow for example, in addition to a part manager.
  46.  *
  47.  * Parts know about the part manager to add nested parts to it.
  48.  * See also KParts::Part::manager() and KParts::Part::setManager().
  49.  */
  50. class KPARTS_EXPORT PartManager : public QObject
  51. {
  52.   Q_OBJECT
  53.   Q_ENUMS( SelectionPolicy )
  54.   Q_PROPERTY( SelectionPolicy selectionPolicy READ selectionPolicy WRITE setSelectionPolicy )
  55.   Q_PROPERTY( bool allowNestedParts READ allowNestedParts WRITE setAllowNestedParts )
  56.   Q_PROPERTY( bool ignoreScrollBars READ ignoreScrollBars WRITE setIgnoreScrollBars )
  57. public:
  58.   /// Selection policy. The default policy of a PartManager is Direct.
  59.   enum SelectionPolicy { Direct, TriState };
  60.  
  61.   /**
  62.    * This extends QFocusEvent::Reason with the non-focus-event reasons for partmanager to activate a part.
  63.    * To test for "any focusin reason", use < ReasonLeftClick.
  64.    * NoReason usually means: explicit activation with @ref setActivePart.
  65.    * @since 3.3
  66.    */
  67.   enum Reason { ReasonLeftClick = 100, ReasonMidClick, ReasonRightClick, NoReason };
  68.  
  69.   /**
  70.    * Constructs a part manager.
  71.    *
  72.    * @param parent The toplevel widget (window / dialog) the
  73.    *               partmanager should monitor for activation/selection
  74.    *               events
  75.    * @param name   The object's name, if any.
  76.    */
  77.   PartManager( QWidget * parent, const char * name = 0L );
  78.   /**
  79.    * Constructs a part manager.
  80.    *
  81.    * @param topLevel The toplevel widget (window / dialog ) the
  82.    *                 partmanager should monitor for activation/selection
  83.    *                 events
  84.    * @param parent   The parent QObject.
  85.    * @param name     The object's name, if any.
  86.    */
  87.   PartManager( QWidget * topLevel, QObject *parent, const char *name = 0 );
  88.   virtual ~PartManager();
  89.  
  90.   /**
  91.    * Sets the selection policy of the partmanager.
  92.    */
  93.   void setSelectionPolicy( SelectionPolicy policy );
  94.   /**
  95.    * Returns the current selection policy.
  96.    */
  97.   SelectionPolicy selectionPolicy() const;
  98.  
  99.   /**
  100.    * Specifies whether the partmanager should handle/allow nested parts
  101.    * or not.
  102.    *
  103.    *  This is a property the shell has to set/specify. Per
  104.    * default we assume that the shell cannot handle nested
  105.    * parts. However in case of a KOffice shell for example we allow
  106.    * nested parts.  A Part is nested (a child part) if its parent
  107.    * object inherits KParts::Part.  If a child part is activated and
  108.    * nested parts are not allowed/handled, then the top parent part in
  109.    * the tree is activated.
  110.    */
  111.   void setAllowNestedParts( bool allow );
  112.   /**
  113.    * @see setAllowNestedParts
  114.    */
  115.   bool allowNestedParts() const;
  116.  
  117.   /**
  118.    * Specifies whether the partmanager should ignore mouse click events for
  119.    * scrollbars or not. If the partmanager ignores them, then clicking on the
  120.    * scrollbars of a non-active/non-selected part will not change the selection
  121.    * or activation state.
  122.    *
  123.    * The default value is false (read: scrollbars are NOT ignored).
  124.    */
  125.   void setIgnoreScrollBars( bool ignore );
  126.   /**
  127.    * @see setIgnoreScrollBars
  128.    */
  129.   bool ignoreScrollBars() const;
  130.  
  131.   /**
  132.    * Specifies which mouse buttons the partmanager should react upon.
  133.    * By default it reacts on all mouse buttons (LMB/MMB/RMB).
  134.    * @param buttonMask a combination of Qt::ButtonState values e.g. Qt::LeftButton | Qt::MidButton
  135.    */
  136.   void setActivationButtonMask( short int buttonMask );
  137.   /**
  138.    * @see setActivationButtonMask
  139.    */
  140.   short int activationButtonMask() const;
  141.  
  142.   /**
  143.    * @internal
  144.    */
  145.   virtual bool eventFilter( QObject *obj, QEvent *ev );
  146.  
  147.   /**
  148.    * Adds a part to the manager.
  149.    *
  150.    * Sets it to the active part automatically if @p setActive is true (default ).
  151.    * Behavior fix in KDE3.4: the part's widget is shown only if @p setActive is true,
  152.    * it used to be shown in all cases before.
  153.    */
  154.   virtual void addPart( Part *part, bool setActive = true );
  155.  
  156.   /**
  157.    * Removes a part from the manager (this does not delete the object) .
  158.    *
  159.    * Sets the active part to 0 if @p part is the activePart() .
  160.    */
  161.   virtual void removePart( Part *part );
  162.  
  163.   /**
  164.    * Replaces @p oldPart with @p newPart, and sets @p newPart as active if
  165.    * @p setActive is true.
  166.    * This is an optimised version of removePart + addPart
  167.    */
  168.   virtual void replacePart( Part * oldPart, Part * newPart, bool setActive = true );
  169.  
  170.   /**
  171.    * Sets the active part.
  172.    *
  173.    * The active part receives activation events.
  174.    *
  175.    * @p widget can be used to specify which widget was responsible for the activation.
  176.    * This is important if you have multiple views for a document/part, like in KOffice.
  177.    */
  178.   virtual void setActivePart( Part *part, QWidget *widget = 0L );
  179.  
  180.   /**
  181.    * Returns the active part.
  182.    **/
  183.   virtual Part *activePart() const;
  184.  
  185.   /**
  186.    * Returns the active widget of the current active part (see activePart()).
  187.    */
  188.   virtual QWidget *activeWidget() const;
  189.  
  190.   /**
  191.    * Sets the selected part.
  192.    *
  193.    * The selected part receives selection events.
  194.    *
  195.    * @p widget can be used to specify which widget was responsible for the selection.
  196.    * This is important if you have multiple views for a document/part, like in KOffice.
  197.    */
  198.   virtual void setSelectedPart( Part *part, QWidget *widget = 0L );
  199.  
  200.   /**
  201.    * Returns the current selected part.
  202.    */
  203.   virtual Part *selectedPart() const;
  204.  
  205.   /**
  206.    * Returns the selected widget of the current selected part (see selectedPart()).
  207.    */
  208.   virtual QWidget *selectedWidget() const;
  209.  
  210.   /**
  211.    * Returns the list of parts being managed by the partmanager.
  212.    */
  213.   const QPtrList<Part> *parts() const;
  214.  
  215.   /**
  216.    * Adds the @p topLevel widget to the list of managed toplevel widgets.
  217.    * Usually a PartManager only listens for events (for activation/selection)
  218.    * for one toplevel widget (and its children), the one specified in the
  219.    * constructor. Sometimes however (like for example when using the KDE dockwidget
  220.    * library), it is necessary to extend this.
  221.    */
  222.   void addManagedTopLevelWidget( const QWidget *topLevel );
  223.   /**
  224.    * Removes the @p topLevel widget from the list of managed toplevel widgets.
  225.    * @see addManagedTopLevelWidget
  226.    */
  227.   void removeManagedTopLevelWidget( const QWidget *topLevel );
  228.  
  229.   /**
  230.    * @return the reason for the last activePartChanged signal emitted.
  231.    * @see Reason
  232.    * @since 3.3
  233.    */
  234.   int reason() const;
  235.  
  236. signals:
  237.   /**
  238.    * Emitted when a new part has been added.
  239.    * @see addPart()
  240.    **/
  241.   void partAdded( KParts::Part *part );
  242.   /**
  243.    * Emitted when a part has been removed.
  244.    * @see removePart()
  245.    **/
  246.   void partRemoved( KParts::Part *part );
  247.   /**
  248.    * Emitted when the active part has changed.
  249.    * @see setActivePart()
  250.    **/
  251.   void activePartChanged( KParts::Part *newPart );
  252.  
  253. protected:
  254.   /**
  255.    * Changes the active instance when the active part changes.
  256.    * The active instance is used by KBugReport and KAboutDialog.
  257.    * Override if you really need to - usually you don't need to.
  258.    */
  259.   virtual void setActiveInstance( KInstance * instance );
  260.  
  261. protected slots:
  262.   /**
  263.    * Removes a part when it is destroyed.
  264.    **/
  265.   void slotObjectDestroyed();
  266.  
  267.   /**
  268.    * @internal
  269.    */
  270.   void slotWidgetDestroyed();
  271.  
  272.   /**
  273.    * @internal
  274.    */
  275.   void slotManagedTopLevelWidgetDestroyed();
  276. private:
  277.   Part * findPartFromWidget( QWidget * widget, const QPoint &pos );
  278.   Part * findPartFromWidget( QWidget * widget );
  279.  
  280. protected:
  281.   virtual void virtual_hook( int id, void* data );
  282. private:
  283.   PartManagerPrivate *d;
  284. };
  285.  
  286. }
  287.  
  288. #endif
  289.  
  290.